/**
 * @file json_utils.h
 * @brief 通用JSON工具函数头文件
 * @details 提供基于cJSON库的通用JSON数据处理工具函数，包括JSON对象的
 *          创建、解析、操作等功能。适用于各种数据类型的JSON序列化和反序列化。
 * 
 * @author zyb
 * @date 2025-09-27
 * @version 1.0
 * 
 * @note 本文件依赖cJSON库，需要先运行环境配置脚本
 * @see cJSON.h
 */

#ifndef JSON_UTILS_H
#define JSON_UTILS_H

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 错误码定义 ==================== */

/**
 * @brief JSON操作结果类型
 * @details 定义JSON操作的各种结果状态
 */
typedef enum {
    JSON_RESULT_SUCCESS = 0,           /* 操作成功 */
    JSON_RESULT_INVALID_PARAM = -1,    /* 无效参数 */
    JSON_RESULT_INVALID_JSON = -2,     /* 无效JSON */
    JSON_RESULT_MEMORY_ERROR = -3,     /* 内存错误 */
    JSON_RESULT_PARSE_ERROR = -4,      /* 解析错误 */
    JSON_RESULT_TYPE_ERROR = -5,       /* 类型错误 */
    JSON_RESULT_NOT_FOUND = -6         /* 未找到 */
} json_result_t;

/* ==================== 函数声明 ==================== */

/**
 * @brief 初始化JSON工具
 * @details 初始化JSON工具模块
 * 
 * @return 初始化结果
 *         - 0: 初始化成功
 *         - 非0: 初始化失败
 */
int json_utils_init(void);

/**
 * @brief 销毁JSON工具
 * @details 清理JSON工具资源
 */
void json_utils_destroy(void);

/* ==================== JSON对象创建 ==================== */

/**
 * @brief 创建JSON对象
 * @details 创建一个新的JSON对象
 * 
 * @return JSON对象指针，失败返回NULL
 */
void* json_utils_create_object(void);

/**
 * @brief 创建JSON数组
 * @details 创建一个新的JSON数组
 * 
 * @return JSON数组指针，失败返回NULL
 */
void* json_utils_create_array(void);

/**
 * @brief 创建JSON字符串
 * @details 创建一个JSON字符串值
 * 
 * @param string 字符串内容
 * @return JSON字符串指针，失败返回NULL
 */
void* json_utils_create_string(const char *string);

/**
 * @brief 创建JSON数字
 * @details 创建一个JSON数字值
 * 
 * @param number 数字值
 * @return JSON数字指针，失败返回NULL
 */
void* json_utils_create_number(double number);

/**
 * @brief 创建JSON布尔值
 * @details 创建一个JSON布尔值
 * 
 * @param boolean 布尔值
 * @return JSON布尔指针，失败返回NULL
 */
void* json_utils_create_bool(bool boolean);

/* ==================== JSON对象操作 ==================== */

/**
 * @brief 添加字符串到JSON对象
 * @details 向JSON对象添加字符串字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param string 字符串值
 * @return 操作结果
 */
json_result_t json_utils_add_string_to_object(void *object, const char *name, const char *string);

/**
 * @brief 添加数字到JSON对象
 * @details 向JSON对象添加数字字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param number 数字值
 * @return 操作结果
 */
json_result_t json_utils_add_number_to_object(void *object, const char *name, double number);

/**
 * @brief 添加布尔值到JSON对象
 * @details 向JSON对象添加布尔字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param boolean 布尔值
 * @return 操作结果
 */
json_result_t json_utils_add_bool_to_object(void *object, const char *name, bool boolean);

/**
 * @brief 添加对象到JSON对象
 * @details 向JSON对象添加子对象字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param item 子对象
 * @return 操作结果
 */
json_result_t json_utils_add_item_to_object(void *object, const char *name, void *item);

/**
 * @brief 添加项目到JSON数组
 * @details 向JSON数组添加项目
 * 
 * @param array JSON数组
 * @param item 要添加的项目
 * @return 操作结果
 */
json_result_t json_utils_add_item_to_array(void *array, void *item);

/* ==================== JSON对象解析 ==================== */

/**
 * @brief 解析JSON字符串
 * @details 将JSON字符串解析为JSON对象
 * 
 * @param json_string JSON字符串
 * @return JSON对象指针，失败返回NULL
 */
void* json_utils_parse(const char *json_string);

/**
 * @brief 获取JSON对象中的字符串
 * @details 从JSON对象中获取字符串字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @return 字符串指针，失败返回NULL
 */
const char* json_utils_get_string(void *object, const char *name);

/**
 * @brief 获取JSON对象中的数字
 * @details 从JSON对象中获取数字字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param number 输出数字值
 * @return 操作结果
 */
json_result_t json_utils_get_number(void *object, const char *name, double *number);

/**
 * @brief 获取JSON对象中的布尔值
 * @details 从JSON对象中获取布尔字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param boolean 输出布尔值
 * @return 操作结果
 */
json_result_t json_utils_get_bool(void *object, const char *name, bool *boolean);

/**
 * @brief 获取JSON对象中的子对象
 * @details 从JSON对象中获取子对象字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @return 子对象指针，失败返回NULL
 */
void* json_utils_get_object(void *object, const char *name);

/**
 * @brief 获取JSON对象中的数组
 * @details 从JSON对象中获取数组字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @return 数组指针，失败返回NULL
 */
void* json_utils_get_array(void *object, const char *name);

/**
 * @brief 获取数组大小
 * @details 获取JSON数组的大小
 * 
 * @param array JSON数组
 * @return 数组大小，失败返回-1
 */
int json_utils_get_array_size(void *array);

/**
 * @brief 获取数组中的项目
 * @details 从JSON数组中获取指定索引的项目
 * 
 * @param array JSON数组
 * @param index 索引
 * @return 项目指针，失败返回NULL
 */
void* json_utils_get_array_item(void *array, int index);

/* ==================== JSON序列化 ==================== */

/**
 * @brief 将JSON对象转换为字符串
 * @details 将JSON对象序列化为格式化的字符串
 * 
 * @param object JSON对象
 * @return JSON字符串，需要调用者释放内存
 */
char* json_utils_print(void *object);

/**
 * @brief 将JSON对象转换为紧凑字符串
 * @details 将JSON对象序列化为紧凑的字符串（无格式化）
 * 
 * @param object JSON对象
 * @return JSON字符串，需要调用者释放内存
 */
char* json_utils_print_unformatted(void *object);

/* ==================== 内存管理 ==================== */

/**
 * @brief 删除JSON对象
 * @details 释放JSON对象占用的内存
 * 
 * @param object JSON对象
 */
void json_utils_delete(void *object);

/**
 * @brief 释放JSON字符串
 * @details 释放由json_utils_print分配的内存
 * 
 * @param json_string JSON字符串
 */
void json_utils_free_string(char *json_string);

/* ==================== 工具函数 ==================== */

/**
 * @brief 检查JSON对象是否有效
 * @details 检查JSON对象是否为有效对象
 * 
 * @param object JSON对象
 * @return true: 有效, false: 无效
 */
bool json_utils_is_valid(void *object);

/**
 * @brief 检查JSON对象是否为指定类型
 * @details 检查JSON对象的类型
 * 
 * @param object JSON对象
 * @param type_name 类型名称 ("object", "array", "string", "number", "boolean")
 * @return true: 匹配, false: 不匹配
 */
bool json_utils_is_type(void *object, const char *type_name);

/**
 * @brief 获取JSON错误信息
 * @details 获取最后一次JSON操作的错误信息
 * 
 * @return 错误信息字符串
 */
const char* json_utils_get_error(void);

#ifdef __cplusplus
}
#endif

#endif /* JSON_UTILS_H */
